Redesign as a complete STFT/ISTFT toolkit (0.4, breaking)#3
Merged
Conversation
Ground-up rewrite turning the single-file 0.3 streaming STFT into a full transform toolkit. Removes the old STFT type, WindowType enum, FromF64 trait and log10_positive function. Correctness fixes (were part of the 0.3 contract): - n_freqs is now fft_size/2 + 1, including the Nyquist bin (was fft_size/2, which dropped it). - bin frequencies are now k*fs/fft_size (were k*fs/(2*(n_freqs-1))). Added: - Stft/StftBuilder: streaming (append/ready/process_into/step/columns) and one-shot spectrogram() batch with centered framing (reflect/edge/zero pad) and optional rayon parallelism. - Istft/IstftBuilder: weighted overlap-add inverse for perfect reconstruction; Stft::inverse() mirrors a forward transform. - Window/WindowFunction/Symmetry: 14 window families in periodic and symmetric variants, with cached sum and sum-of-squares. - Scaling (none/magnitude/density) and PadMode. - spectrum helpers: magnitude, power, phase, dB conversions. - mel feature: mel filterbank, mel scales and an orthonormal DCT-II for MFCCs (librosa-compatible defaults), no extra dependencies. - Optional ndarray (Array2 output), rayon, serde integrations. - no_std support (with alloc) for the window, spectrum and mel math. Changed: - FFT backend switched to realfft (real-only): ~2x faster, half the memory on real input. - #![forbid(unsafe_code)] across the crate; safety-dance badge. Tooling: - New CI (fmt, clippy, MSRV, no_std build, docs, cargo-deny, coverage), rustfmt.toml, deny.toml, CHANGELOG.md, dependabot. Removed dead .travis.yml. README rewritten with examples and a 0.3 migration table. Tests: analytic correctness tests plus proptest linearity and STFT/ISTFT round-trip properties; runnable examples.
There was a problem hiding this comment.
Pull request overview
This PR redesigns ruststft into a broader STFT/ISTFT toolkit with builder-based APIs, real-FFT-backed processing, window/spectrum/mel helpers, no-std-compatible math modules, and expanded project automation.
Changes:
- Replaces the legacy
STFTAPI withStft,Istft,Spectrogram, builders, scaling, padding, and error types. - Adds window generation, spectrum utilities, optional mel/MFCC support, examples, benches, and expanded tests.
- Updates package metadata, README, changelog, CI/dependabot/cargo-deny/task runner configuration, and removes Travis CI.
Reviewed changes
Copilot reviewed 26 out of 26 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
Cargo.toml |
Updates crate metadata, features, dependencies, lints, examples, and version. |
src/lib.rs |
Rebuilds crate root, feature gates, docs, and public re-exports. |
src/config.rs |
Adds Scaling and PadMode configuration enums. |
src/error.rs |
Adds StftError and display/error implementations. |
src/sample.rs |
Adds shared sample trait abstraction and casting helper. |
src/spectrum.rs |
Adds magnitude, power, phase, and dB conversion helpers. |
src/stft.rs |
Adds forward STFT builder and streaming processor. |
src/batch.rs |
Adds one-shot spectrogram generation and Spectrogram container. |
src/istft.rs |
Adds inverse STFT builder, WOLA reconstruction, and Stft::inverse. |
src/mel.rs |
Adds mel scale/filterbank and DCT-II support behind the mel feature. |
src/window/mod.rs |
Adds typed window API and window family definitions. |
src/window/functions.rs |
Adds raw f64 window coefficient generators. |
tests/lib.rs |
Rewrites integration tests for the new public API. |
tests/proptests.rs |
Adds property tests for STFT linearity and round-trip reconstruction. |
examples/spectrogram.rs |
Adds spectrogram/chirp example. |
examples/roundtrip.rs |
Adds STFT→ISTFT reconstruction example. |
examples/mfcc.rs |
Adds mel/MFCC example. |
benches/lib.rs |
Rewrites Criterion benchmarks for the new API. |
README.md |
Rewrites user-facing documentation and migration guide. |
CHANGELOG.md |
Adds 0.4.0 changelog entry. |
Taskfile.dist.yaml |
Adds common development, test, build, docs, and CI tasks. |
rustfmt.toml |
Adds rustfmt edition configuration. |
deny.toml |
Adds cargo-deny policy configuration. |
.github/workflows/ci.yml |
Adds expanded GitHub Actions CI workflow. |
.github/dependabot.yml |
Adds Dependabot configuration. |
.travis.yml |
Removes obsolete Travis CI configuration. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Adds a `wasm_simd` feature that forwards to `realfft/wasm_simd` (and thus `rustfft/wasm_simd`). It implies `std` because the FFT backend does, so it cannot half-activate the optional realfft dependency. No effect off wasm32; on wasm32 it enables the simd128 kernels when built with `-C target-feature=+simd128`.
- Taskfile `test:no-std`: build the library only instead of running the integration tests, which require `std` (they import `Stft`). - Remove the obsolete `.github/workflows/rust.yml`; the new `ci.yml` replaces it and the duplicate would double-run on every push/PR. - Correct the centered-padding docs on `StftBuilder::center` and `PadMode` to say `frame_len / 2` (the value the implementation uses), not `fft_size / 2`. - Fix the chirp in examples/spectrogram.rs to integrate the linear frequency sweep, so it actually starts at 200 Hz (a bare sin(pi*f*t) starts at f0/2 = 100 Hz).
sunsided
force-pushed
the
feature/v0.4-redesign
branch
from
f2ea2e9 to
6523ee1
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Rebuilds
ruststftfrom a single-file streaming STFT into a full short-time Fourier transform toolkit: forward and inverse transforms, a real window library, batch and streaming APIs, spectrum/decibel helpers, and optional mel spectrograms and MFCCs. The public API is now encapsulated behind builders instead of exposing struct internals.Why now
The 0.3 API hard-codes two spectral bugs into its contract and exposes every field as
pub, so neither could be fixed without breaking changes. This release takes the break deliberately, bumps to 0.4, and sets up a path to a stable 1.0.Key changes
realfft(real-input only): roughly 2x faster and half the memory of the previous full complex FFT on real data.fft_size/2 + 1(the Nyquist bin was previously dropped), and bin frequencies are nowk*fs/fft_size(previously off).Stft/StftBuilder: streaming (append/ready/process_into/step/columns) plus one-shotspectrogram()with centered framing (reflect/edge/zero padding) and optionalrayonparallelism.Istft/IstftBuilder: weighted overlap-add inverse for perfect reconstruction;Stft::inverse()mirrors a forward transform.Window/WindowFunction/Symmetrycovering 14 families in periodic and symmetric variants.melfeature: mel filterbank, mel scales and an orthonormal DCT-II for MFCCs with librosa-compatible defaults, no extra dependencies.ScalingandPadMode,spectrumhelpers (magnitude/power/phase/dB), optionalndarray/serde,no_std(withalloc) for the non-FFT math, and#![forbid(unsafe_code)].deny.toml,rustfmt.toml,CHANGELOG.md, dependabot; removed the dead Travis config; README rewritten with a 0.3 migration table.Risks / notes
STFTtype,WindowType,FromF64andlog10_positiveare removed. Existing users must migrate; the README has a mapping table.no_stdis partial: the FFT processors require the defaultstdfeature because the backend needsstd. The window, spectrum and mel math build without it.How to review
Start at
src/lib.rsfor the module map and feature gating. Readsrc/stft.rs(the forward transform and builder) thensrc/istft.rs(overlap-add inverse) - those two carry the core algorithm and the reconstruction math. Checksrc/batch.rsfor centering/padding and the parallel frame path. Skimsrc/window/andsrc/mel.rsas mostly self-contained math.tests/lib.rsandtests/proptests.rsshow the intended usage and the correctness contracts (Nyquist bin, frequency mapping, round-trip reconstruction, linearity).